<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.10"/>
<title>axiethernet: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.gif"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">axiethernet
   </div>
   <div id="projectbrief">Xilinx SDK Drivers API Documentation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.10 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Overview</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="globals.html"><span>APIs</span></a></li>
      <li><a href="files.html"><span>File&#160;List</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">axiethernet Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The Xilinx AXI Ethernet MAC driver component. This driver supports hard Ethernet core for Virtex-6(TM) devices and soft Ethernet core for Spartan-6(TM) and other supported devices. The supported speed can be 10/100/1000 Mbps and can reach upto 2000/2500 Mbps (1000Base-X versions).</p>
<p>For a full description of AXI Ethernet features, please see the hardware spec. This driver supports the following features:</p><ul>
<li>Memory mapped access to host interface registers</li>
<li>Virtual memory support</li>
<li>Unicast, broadcast, and multicast receive address filtering</li>
<li>Full duplex operation</li>
<li>Automatic source address insertion or overwrite (programmable)</li>
<li>Automatic PAD &amp; FCS insertion and stripping (programmable)</li>
<li>Flow control</li>
<li>VLAN frame support</li>
<li>Pause frame support</li>
<li>Jumbo frame support</li>
<li>Partial and full checksum offload</li>
<li>Extended multicast addresses to 2**23.</li>
<li>Extended VLAN translation, tagging and stripping supports.</li>
</ul>
<h2>Driver Description</h2>
<p>The device driver enables higher layer software (e.g., an application) to configure a Axi Ethernet device. It is intended that this driver be used in cooperation with another driver (FIFO or DMA) for data communication. This device driver can support multiple devices even when those devices have significantly different configurations.</p>
<h2>Initialization &amp; Configuration</h2>
<p>The <a class="el" href="struct_x_axi_ethernet___config.html" title="This typedef contains configuration information for a Axi Ethernet device. ">XAxiEthernet_Config</a> structure can be used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on hardware build properties, although, other methods are allowed and currently used in some systems.</p>
<p>To support multiple runtime loading and initialization strategies employed by various operating systems, the driver instance can be initialized using the XAxiEthernet_CfgInitialze() routine.</p>
<h2>Interrupts and Asynchronous Callbacks</h2>
<p>The driver has no dependencies on the interrupt controller. It provides no interrupt handlers. The application/OS software should set up its own interrupt handlers if required.</p>
<h2>Device Reset</h2>
<p>When a Axi Ethernet device is connected up to a FIFO or DMA core in hardware, errors may be reported on one of those cores (FIFO or DMA) such that it can be determined that the Axi Ethernet device needs to be reset. If a reset is performed, the calling code should also reconfigure and reapply the proper settings in the Axi Ethernet device.</p>
<p>When a Axi Ethernet device reset is required, <a class="el" href="group__axiethernet__v5__0.html#ga091a291d11f394e3eaf0b79195666d9f" title="XAxiEthernet_Reset does not perform a soft reset of the AxiEthernet core. ">XAxiEthernet_Reset()</a> should be utilized.</p>
<h2>Virtual Memory</h2>
<p>This driver may be used in systems with virtual memory support by passing the appropriate value for the <em>EffectiveAddress</em> parameter to the <a class="el" href="group__axiethernet__v5__0.html#ga73871df4ff59ae908c63c51db94f1a90" title="XAxiEthernet_CfgInitialize initializes an AXI Ethernet device along with the InstancePtr that referen...">XAxiEthernet_CfgInitialize()</a> routine.</p>
<h2>Transfering Data</h2>
<p>The Axi Ethernet core by itself is not capable of transmitting or receiving data in any meaningful way. Instead the Axi Ethernet device need to be connected to a FIFO or DMA core in hardware.</p>
<p>This Axi Ethernet driver is modeled in a similar fashion where the application code or O/S adapter driver needs to make use of a separate FIFO or DMA driver in connection with this driver to establish meaningful communication over Ethernet.</p>
<h2>Checksum Offloading</h2>
<p>If configured, the device can compute a 16-bit checksum from frame data. In most circumstances this can lead to a substantial gain in throughput.</p>
<p>The checksum offload settings for each frame sent or received are transmitted through the AXI4-Stream interface in hardware. What this means is that the checksum offload feature is indirectly controlled in the Axi Ethernet device through the driver for DMA core connected to the Axi Ethernet device.</p>
<p>Refer to the documentation for DMA driver used for data communication on how to set the values for the relevant AXI4-Stream control words.</p>
<p>Since this hardware implementation is general purpose in nature system software must perform pre and post frame processing to obtain the desired results for the types of packets being transferred. Most of the time this will be TCP/IP traffic.</p>
<p>TCP/IP and UDP/IP frames contain separate checksums for the IP header and UDP/TCP header+data. For partial checksum offloading (enabled while configuring the hardware), the IP header checksum cannot be offloaded. Many stacks that support offloading will compute the IP header if required and use hardware to compute the UDP/TCP header+data checksum. There are other complications concerning the IP pseudo header that must be taken into consideration. Readers should consult a TCP/IP design reference for more details.</p>
<p>For full checksum offloading (enabled while configuring the hardware), the IPv4 checksum calculation and validation can also be offloaded at the harwdare. Full checksum offload is supported only under certain conditions. IP checksum offload will be supported on valid IP datagrams that meet the following conditions.</p><ul>
<li>If present, the VLAN header is 4 bytes long</li>
<li>Encapsulation into the Ethernet frame is either Ethernet II or Ethernet SNAP format</li>
<li>Only IPv4 is supported. IPv6 is not supported.</li>
<li>IP header is a valid length TCP/UDP checksum offloading will be supported on valid TCP/UDP segments that meet the following conditions.</li>
<li>Encapsulated in IPv4 (IPv6 is not supported)</li>
<li>Good IP header checksum</li>
<li>No fragmentation</li>
<li>TCP or UDP segment When full checksum offload is enabled, the hardware does the following:</li>
<li>Calculates the IP header checksum and inserts it in the IP header.</li>
<li>Calculates the TCP/UDP Pseudo header from IP header.</li>
<li>Calculates TCP/UDP header from, TCP/UDP psedu header, TCP/UDP header and TCP/UDP payload.</li>
<li>On the receive path, it again calculates all the above and validates for IP header checksum and TCP/UDP checksum.</li>
</ul>
<p>There are certain device options that will affect the checksum calculation performed by hardware for Tx:</p>
<ul>
<li>FCS insertion disabled (XAE_FCS_INSERT_OPTION): software is required to calculate and insert the FCS value at the end of the frame, but the checksum must be known ahead of time prior to calculating the FCS. Therefore checksum offloading cannot be used in this situation.</li>
</ul>
<p>And for Rx:</p>
<ul>
<li>FCS/PAD stripping disabled (XAE_FCS_STRIP_OPTION): The 4 byte FCS at the end of frame will be included in the hardware calculated checksum. software must subtract out this data.</li>
<li>FCS/PAD stripping disabled (XAE_FCS_STRIP_OPTION): For frames smaller than 64 bytes, padding will be included in the hardware calculated checksum. software must subtract out this data. It may be better to allow the TCP/IP stack verify checksums for this type of packet.</li>
<li>VLAN enabled (XAE_VLAN_OPTION): The 4 extra bytes in the Ethernet header affect the hardware calculated checksum. software must subtract out the 1st two 16-bit words starting at the 15th byte.</li>
</ul>
<h3>Transmit Checksum Offloading</h3>
<p>For partial checksum offloading, for the TX path, the software can specify where in the frame the checksum calculation is to start, where the result should be inserted, and a seed value. The checksum is calculated from the start point through the end of frame.</p>
<p>For full checksum offloading, for the TX path, the software just need to enable Full Checksum offload in the appropriate AXI4-Stream Control word on a per packet basis.</p>
<p>The checksum offloading settings are sent in the transmit AXI4 Stream control words. The relevant control word fields are described in brief below. Refer to the Axi Ethernet hardware specification for more details.</p>
<h4>AXI4-Stream Control Word 0:</h4>
<pre>
	Bits  1-0  : Transmit Checksum Enable: 	01 - Partial checsum offload,
						10 - Full checksum offload
						00 - No checksum offloading
						11 - Not used, reserved
	Bits 27-2  : Reserved
	Bits 31-28 : Used for AXI4-Stream Control Mode flag
*</pre><h4>AXI4-Stream Control Word 1:</h4>
<pre>
	Bits 31-16 (MSB): Transmit Checksum Calculation Starting Point: Offset
			  in the frame where checksum calculation should begin.
			  Relevant only for partial checksum offloading.
	Bits 15-0  (LSB): Transmit Checksum Insertion Point: Frame offset where
			  the computed checksum value is stored, which should be
			  in the TCP or UDP header.
			  Relevant only for partial checksum offloading.
    </pre><h4>AXI4-Stream Control Word 2:</h4>
<pre>
	Bits 31-16 (MSB): Reserved
	Bits  0-15 (LSB): Transmit Checksum Calculation Initial Value: Checksum
			  seed value.
			  Relevant only for partial checksum offloading.
*</pre><h3>Receive Checksum Offloading</h3>
<p>For partial checksum offload on the RX path, the 15th byte to end of frame is check summed. This range of bytes is the entire Ethernet payload (for non-VLAN frames).</p>
<p>For full checksum offload on the RX path, both the IP and TCP checksums are validated if the packet meets the specified conditions.</p>
<p>The checksum offloading information is sent in the receive AXI4-Stream status words. There are 4 relevant status words available. However only the relevant status words are described in brief below. Refer to the Axi Ethernet hardware specification for more details.</p>
<h4>AXI4-Stream Status Word 0:</h4>
<pre>
	Bits 31-28 (MSB): Always 0x5 to represent receive status frame
	Bits 27-16	: Undefined
	Bits 15-0  (LSB): MCAST_ADR_U. Upper 16 bits of the multicast
			  destination address of the frame.</pre><pre>*</p><h4>AXI4-Stream Status Word 1:</h4>
</pre><pre>
*</pre><p> Bits 31-0 : MCAST_ADR_L. The lower 32 bits of the multicast destination address.</p>
<h4>AXI4-Stream Status Word 2:</h4>
<p>Bits 5-3 : Specifies the receive full checksum status. This is relevant only for full checksum offloading. 000 -&gt; Neither the IP header nor the TCP/UDP checksums were checked. 001 -&gt; The IP header checksum was checked and was correct. The TCP/UDP checksum was not checked. 010 -&gt; Both the IP header checksum and the TCP checksum were checked and were correct. 011 -&gt; Both the IP header checksum and the UDP checksum were checked and were correct. 100 -&gt; Reserved. 101 -&gt; The IP header checksum was checked and was incorrect. The TCP/UDP checksum was not checked. 110 -&gt; The IP header checksum was checked and is correct but the TCP checksum was checked and was incorrect. 111 -&gt; The IP header checksum was checked and is correct but the UDP checksum was checked and was incorrect.</p>
<h4>AXI4-Stream Status Word 3:</h4>
<p>Bits 31-16 : T_L_TPID. This is the value of 13th and 14th byte of the frame. Bits 15-0 : Receive Raw Checksum: Computed checksum value</p>
<h4>AXI4-Stream Status Word 3:</h4>
<p>Bits 31-16 : VLAN_TAG. Value of 15th and 16th byte of the frame. Bits 15-0 : RX_BYTECNT. Received frame length.</p>
<h2>Extended multicast</h2>
<p>(XAE_EXT_MULTICAST_OPTION): Allow and perform address filtering more than 4 multicast addresses. Hardware requires to enable promiscuous mode (XAE_PROMISCUOUS_OPTION) and disable legacy multicast mode (XAE_MULTICAST_OPTION) for this feature to work.</p>
<h2>Extended VLAN</h2>
<h3>TX/RX VLAN stripping</h3>
<p>(XAE_EXT_[T|R]XVLAN_STRP_OPTION) handles transmit/receive one VLAN tag stripping in Ethernet frames. To enable this option, hardware requires to build with this feature and enable (XAE_FCS_INSERT_OPTION), (XAE_FCS_STRP_OPTION) and disable (XAE_VLAN_OPTION). Supports three modes, -XAE_VSTRP_NONE : no stripping -XAE_VSTRP_ALL : strip one tag from all frames -XAE_VSTRP_SELECT : strip one tag from selected frames</p>
<h3>TX/RX VLAN translation</h3>
<p>(XATE_EXT_[T|R]XVLAN_TRAN_OPTION) handles transmit/receive one VLAN tag translation in Ethernet frames. To enable this option, hardware requires to build with this feature and enable (XATE_FCS_INSERT_OPTION), (XAE_FCS_STRP_OPTION), and disable (XAE_VLAN_OPTION).</p>
<h3>TX/RX VLAN tagging</h3>
<p>(XAE_EXT_[T|R]XVLAN_TAG_OPTION) adds transmit/receive one VLAN tag in Ethernet frames. To enable this option, hardware requires to build with this feature and enable (XAE_FCS_INSERT_OPTION), (XAE_FCS_STRP_OPTION), (XAE_JUMBO_OPTION) and disable (XAE_VLAN_OPTION). Support four modes, -XAE_VTAG_NONE : no tagging -XAE_VTAG_ALL : tag all frames -XAE_VTAG_EXISTED : tag already tagged frames -XAE_VTAG_SELECT : tag selected already tagged frames</p>
<h2>PHY Communication</h2>
<p>Prior to PHY access, the MDIO clock must be setup. This driver will set a safe default that should work with AXI4-Lite bus speeds of up to 150 MHz and keep the MDIO clock below 2.5 MHz. If the user wishes faster access to the PHY then the clock divisor can be set to a different value (see <a class="el" href="group__axiethernet__v5__0.html#ga2b33bc77237bf039c02d4619a811aed6" title="XAxiEthernet_PhySetMdioDivisor sets the MDIO clock divisor in the Axi Ethernet,specified by InstanceP...">XAxiEthernet_PhySetMdioDivisor()</a>).</p>
<p>MII register access is performed through the functions XAxiEthernet_PhyRead() and XAxiEthernet_PhyWrite().</p>
<h2>Link Sync</h2>
<p>When the device is used in a multi speed environment, the link speed must be explicitly set using <a class="el" href="group__axiethernet__v5__0.html#gab2d0106f26a1a2e1f2b902dc0a2822c9" title="XAxiEthernet_SetOperatingSpeed sets the current operating link speed. ">XAxiEthernet_SetOperatingSpeed()</a> and must match the speed PHY has negotiated. If the speeds are mismatched, then the MAC will not pass traffic.</p>
<p>The application/OS software may use the AutoNegotiation interrupt to be notified when the PHY has completed auto-negotiation.</p>
<h2>Asserts</h2>
<p>Asserts are used within all Xilinx drivers to enforce constraints on argument values. Asserts can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier. By default, asserts are turned on and it is recommended that users leave asserts on during development. For deployment use -DNDEBUG compiler switch to remove assert code.</p>
<h2>Driver Errata</h2>
<ul>
<li>A dropped receive frame indication may be reported by the driver after calling <a class="el" href="group__axiethernet__v5__0.html#ga4e952a55f342f176ba9ec2b49e2e47cb" title="XAxiEthernet_Stop gracefully stops the Axi Ethernet device as follows: ">XAxiEthernet_Stop()</a> followed by <a class="el" href="group__axiethernet__v5__0.html#ga2cfa48d42e55238f6f30aff6d658e4fe" title="XAxiEthernet_Start starts the Axi Ethernet device as follows: ">XAxiEthernet_Start()</a>. This can occur if a frame is arriving when stop is called.</li>
<li>On Rx with checksum offloading enabled and FCS/PAD stripping disabled, FCS and PAD data will be included in the checksum result.</li>
<li>On Tx with checksum offloading enabled and auto FCS insertion disabled, the user calculated FCS will be included in the checksum result.</li>
</ul>
<dl class="section note"><dt>Note</dt><dd></dd></dl>
<p>Xilinx drivers are typically composed of two components, one is the driver and the other is the adapter. The driver is independent of OS and processor and is intended to be highly portable. The adapter is OS-specific and facilitates communication between the driver and an OS. <br />
<br />
 This driver is intended to be RTOS and processor independent. Any needs for dynamic memory management, threads or thread mutual exclusion, or cache control must be satisfied by the layer above this driver.</p>
<pre>
  MODIFICATION HISTORY:</pre><pre>  Ver   Who  Date     Changes
  ----- ---- -------- ---------------------------------------------------------
  1.00a asa  6/30/10  First release based on the ll temac driver
  1.01a asa  12/10/10 Added macros XAxiEthernet_IsRxFullCsum and
		      XAxiEthernet_IsTxFullCsum for supporting full checksum
		      offload. The full checksum offload is only supported in
		      newer versions of the core, please refer to the core
		      HW datasheet.
  1.02a asa  2/16/11  Inserted a delay in the driver function
		      XAxiEthernet_Reset in file <a class="el" href="xaxiethernet_8c.html">xaxiethernet.c</a>. This is done
		      because immediately after a core reset none of the
		      AxiEthernet registers are accessible for some duration.
		      Changed the value of XAE_LOOPS_TO_COME_OUT_OF_RST to
		      10000 in file <a class="el" href="xaxiethernet__hw_8h.html">xaxiethernet_hw.h</a>.</pre><pre>  2.00a asa  8/29/11  A new major version of AxiEthernet driver is being
		      released to accomodate the change in avb software. The
		      AxiEthernet hardware v3_00_a has the latest avb
		      hardware which needs a corresponding change in avb
		      software (released in examples/avb folder). This change
		      in avb software is not backwards compatible (which
		      means this avb software will not work with older
		      axiethernet hardware).
		      Hence a new major version of axiethernet is being
		      released.
		      Added defines for Ability Reg, Identification Reg, Rx max
		      Frame and Tx Max Frame registers.
		      Changed define for TEMAC RGMII/SGMII Config (PHYC) Reg.</pre><pre>  3.00a asa  4/10/12  A new major version of AxiEthernet is being released to
		      accomodate the change in AVB example. From AxiEthernet
		      core version 3.01a onwards the AVB implementation has
		      changed. The AVB module is now a part of AxiEthernet IP.
		      Because of this change, the AVB example works only
		      when promiscuous mode is not enabled (unlike earlier
		      implementation where promiscuous mode was required for
		      AVB example to work). Hence the file xavb_example.c is
		      changed so that the core is not put in promiscuous mode.
		      Also since AVB is a part of AxiEthernet some of the
		      register mappings in xavb_hw.h has changed.
		      These changes are not backward compatible which means
		      this changed example will not work for previous versions
		      of cores.
		      Hence a new major version of axiethernet is being
		      released.
  3.01a srt  02/03/13 - Added support for SGMII mode (CR 676793)</p><ul>
<li>Added support for IPI designs (CR 698249)
	     02/14/13 - Added support for Zynq (CR 681136)
  3.02a srt  04/13/13 - Removed Warnings (CR 704998).
             04/24/13 - Modified parameter *_SGMII_PHYADDR to *_PHYADDR, the
                        config parameter C_PHYADDR applies to SGMII/1000BaseX
	                modes of operation
	     04/24/13 - Added support for 1000BaseX mode in examples (_util.c)
		        (CR 704195)
	     04/24/13 - Added support for RGMII mode in examples (_util.c)
  3.02a srt  08/06/13 - Fixed CR 727634:
			  Modified FifoHandler() function logic of FIFO
			  interrupt example to reflect the bit changes in
			  the Interrupt Status Register as per the latest
			  AXI FIFO stream IP.</li>
<li>Fixed CR 721141:
			  Added support to handle multiple instances of
			  AxiEthernet FIFO interface (CR 721141)</li>
<li>Fixed CR 717949:
			  Configures external Marvel 88E1111 PHY based on the
			  AXI Ethernet physical interface type and allows to
			  operate in specific interface mode without changing
			  jumpers on the Microblaze boards. This change is in
			  example_util.c
  3.02a adk 15/11/13 - Fixed CR 761035 removed dependency with fifo in MDD file
  4.0   adk 19/12/13 - Updated as per the New Tcl API's
		asa 30/01/14 - Added defines for 1588 registers and bit masks
					   Added config parameter for SGMII over LVDS</li>
</ul>
</pre><pre>  4.1  adk 21/04/14 - Fixed CR:780537 Changes are Made in the file
		      axiethernet test-app tcl
  4.2  adk 08/08/14 - Fixed CR:810643 SDK generated 'xparamters.h' erroneously
		      generated with errors due to part of '#define' misplaced
		      changes are made in the driver tcl file.
  4.3 adk 29/10/14 -  Added support for generating parameters for SGMII/1000BaseX
		      modes When IP is configured with the PCS/PMA core.
		      Changes are made in the driver tcl file (CR 828796).
  4.4  adk  8/1/15 -  Fixed TCL errors when axiethernet is configured with the
		      Axi stream fifo (CR 835605). Changes are made in the
		      driver tcl file.
  5.0  adk 13/06/15 - Updated the driver tcl for Hier IP(To support User parameters).
  5.0  adk 28/07/15 - Fixed CR:870631 AXI Ethernet with FIFO will fail to
		      Create the BSP if the interrupt pin on the FIFO is unconnected
  </pre> </div></div><!-- contents -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Copyright &copy; 2015 Xilinx Inc. All rights reserved.</li>
  </ul>
</div>
</body>
</html>
